Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Reorder (and restructure) the sections in the README #678

Merged
merged 2 commits into from
Dec 22, 2019
Merged

Reorder (and restructure) the sections in the README #678

merged 2 commits into from
Dec 22, 2019

Conversation

martinholters
Copy link
Member

Previously, the sections were

  • Supported syntax
  • Module Aliases
  • New functions, macros, and methods
  • Renaming
  • New macros
  • Other changes
  • New types
  • Developer tips

This changes the order to

  • Supported syntax
  • New functions and methods
  • New macros
  • New types
  • Renaming
  • Other changes
  • Developer tips

getting rid of the ambiguity where to put new macros and removing the
"Module Aliases" section (if needed, these could probably go into
"Renaming").

Also, the entry from #668 is moved from "Other changes" to "New
functions and methods" as it is a new method.

Finally, presently empty sections get a "None." placeholder entry.

@martinholters martinholters added the no changelog Prevent Tagbot from including in release note label Nov 16, 2019
@martinholters martinholters changed the title Reorder (and restrcuture) the sections in the README Reorder (and restructure) the sections in the README Nov 16, 2019
@martinholters
Copy link
Member Author

As you also have some ideas for the README (#680), mind taking a look here and commenting, @oxinabox?

@oxinabox
Copy link
Contributor

oxinabox commented Nov 18, 2019 •
edited
Loading

I suggest Supported syntax go at the bottom, as the @compat macro is rarely used,
and having it at the top makes it look like all the other things require it

I'm not convinced that we need more than 2 sections listing features.
one about @compat and one about everything else

@martinholters
Copy link
Member Author

Yes, let's trim down the number of sections. I wasn't sure about keeping the empty ones anyway. If things start to become a mess, we can still re-introduce new sections as needed then.

Looking back at when we still had @compat entries in the README, they were always explicitly mentioning the macro, e.g. "@compat foo(; x, y) makes x and y required keyword arguments". So I'm not even convinced they need their own section. (Anyway, until development of Julia 2 starts, it seems unlikely that we will need to use @compat much.)

So maybe we can just collect all supported features in one section, tentatively title "Supported features"? That would leave

  • Usage
  • Supported features
  • Devloper tips

Nice and clean 😄
What do people think?

@oxinabox
Copy link
Contributor

Sounds good to me

@martinholters
Restructure sections in the README
fa826b3 
Previously, the sections were
* Usage
* Supported syntax
* Module Aliases
* New functions, macros, and methods
* Renaming
* New macros
* Other changes
* New types
* Developer tips

This changes them to just
* Usage
* Supported features
* Developer tips
@martinholters martinholters mentioned this pull request Nov 18, 2019
Closed
@martinholters
Copy link
Member Author

Incorporated the sorting from #680 (newest on top) here and will merge soonish unless anyone objects.

@martinholters martinholters merged commit 0df59e6 into master Dec 22, 2019
@martinholters martinholters deleted the mh/readme-sections branch December 22, 2019 09:06
@martinholters martinholters mentioned this pull request Dec 25, 2019
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers
No reviews
Assignees
No one assigned
Labels
no changelog Prevent Tagbot from including in release note
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
2 participants
@martinholters @oxinabox